Map Editor Scripting
The NoX map editor has the ability to edit all of the scripts used in single player, multiplayer, and quest maps. Scripts are what make the explosion of an NPC teleporting, the music in the area, the deadly arrow traps, almost anything possible! To make use of the most recent function definitions, download the latest pack: http://www.mediafire.com/?0lyewaycg4r1qv5 Script Use Learning how to use scripts in NoX maps is, by far, the most difficult aspect of the editor. The simple functions, like unlocking a door, aren't that complicated; contrary to a boss NPC with a load of variables required to fulfill its purpose; but both require knowledge of proper syntax, variable use, math and logic, and a little uncommon sense to keep the whole thing from collapsing and crashing the game (though that last one comes up a little less often unless you're trying to be a revolutionary in NoX scripting). It isn't actually very overwhelming to make good use of all of them once you get used to how they work. Pointers Before anything else is said, one thing must be stated first, as it may very well be one of the most important parts of NoX scripting; what is a pointer? A pointer is basically a string or value that is used to reference an object, waypoint, wall, or group, among other things. Without pointers, a function is practically internal, and won't have any effect on what happens in the game. The method of creating a pointer varies depending on what the pointer is being made for. For objects, you must select the target and go to its Properties menu. Then, you click the Xtra Bytes checkbox until the field labeled "Script Name" is not greyed out. In that field is where you input the name of the pointer. For waypoints, all you must do is select the waypoint you want to allocate the pointer to, and rename it. (Waypoints created afterwards will share the name in the field.) For groups, all you need to do is create a group (though groups have been known to be unreliable). For all of those, you can add the phrase "nameofthemap:" on the front without changing the pointer. Walls can only be referenced either in groups or directly in the script; this will be explained next. Once pointers have been allocated, you can use them in the script, using functions with the explicit purpose of representing them. Such functions include: Object("Pointer") Waypoint("Pointer") Wall(50,50) ObjectGroup("Pointer") WaypointGroup("Pointer") WallGroup("Pointer") For most of the functions, you only need to put the name of the pointer into the brackets (with quotations surrounding it). For individual walls, though, you must determine the wall coordinates of the wall you are trying to reference (more on that here) and place the x- and y-values in the blanks. Using these functions in their entirety every time you want to mention a pointer can get cumbersome, and also bloat the script size. To prevent this from happening, and with many other uses, you can use variables to make a much quicker, much lighter reference. To use variables as pointers, you must allocate them as such: Gvar4 = Object("Pointer") Gvar5 = Waypoint("Pointer") var0 = Wall(50,50) etc. Once you have done this, you can use them much more accessibly just by using Gvar4 (or whatever variable the pointer was allocated to) in place of the whole function. For example, a function could change from this: Move(Object("BadBear"),Waypoint("BearPoint")) to this: Move(Gvar4,Gvar5) Now, the script is much smaller and more manageable. These values can be used over and over again, in different parts of the scripts. Syntax Learning how to use proper syntax is crucial if you intend to create anything more than rudimentary functions. It's necessary to learn how scripts are supposed to be built, and doing so can help to avoid numerous conflicts. Syntax is actually relatively easy to understand in the script editor. There are a few basic structures for commands to follow; the first of which is the command alone: Command(Variable,"String",Command(Blah)) Now, let's examine the structure of this mockup command: *The first part is, of course, the declaration of the command itself. This tells the script what to perform. *Next, there is an open bracket. This bracket will need to close at the end of the command. *Next up comes an argument. Arguments come in a variety of types; most commonly, in variables, values, strings, and certain commands. The type of argument each one is is dependent on the purpose of the function, and the amount of arguments required is dependent on the command. (More on arguments below.) *Every argument is followed by a comma, with no space after the comma, unless it's the last argument. *The above two repeat until they reach the end of the command. Then, a closed bracket is placed to complete the command. Arguments Arguments are the part of each command that help to clarify exactly what that command is supposed to do. How they do this is specific on what the command desires. They may be specified as a value, a variable, a string, or even another command, depending on the function. Values are the easiest to implement, since they don't rely on any other data or commands to act validly. However, a value can only consist of a number, and there are not many situations where a value will be useful by itself. Variables are similar to values, except that they represent specific data and must be declared beforehand. They aren't limited to numerical values like values; they can also be strings, objects, locations, and even other commands. Here is an example of a script making use of both types: ChangeGold(Gvar1,1000000) In this example, the first argument is a variable, and the second a value. The variable represents the entity that called the function the command is in, and the value represents how much gold that entity will receive. Certain Commands are often used to designate variables within commands. They are similar to variables except that they will return a value in correspondence to their purpose, and only represent very specific data depending on what command is used. Some examples of commands suitable for use inside commands are: GetHost() GetGold(Arg) GetObjectX(Arg) Waypoint(Arg) Object(Arg) GetCaller(Arg) Commands can also be designated to variables, which is a good idea if you plan to use the same command several times in a script: Gvar4 = Object("Bear1") var0 = Waypoint("Waypoint") However, if the pointer being referred to is dynamic (such as an object's X coordinate), you must use the command itself to get an accurate value. Finally, Strings are used to reference pointers and data using words and phrases. They are used very often to designate variables to pointers, such as in the example above. Strings must be surrounded by quotations ( "" ). Like commands, what they represent will differ from command to command; the most common uses for strings are for pointers, chat strings, objects, and spells or enchants. Following is an example for each of these uses: var0 = Object("TheObject") Chat(Gvar1,"This is a string.") var1 = Create("RedPotion",Gvar4) CastSpellOn("SPELL_LIGHT",Gvar5,Gvar1) Enchant(Gvar1,"ENCHANT_BURNING",f40) Logic/Math Learning proper syntax will give you limited access to what is possible in script modification; however, with a grasp on Logic, it is possible to create much more elaborate and impressive scripts than the simple, linear functions created with syntax alone. Much of this logic is fairly basic, but it isn't always easy to implement without knowing how it can be used. Following are some existing logical arguments: = : Used to represent something : Is equal to > : Is greater than < : Is less than >= : Is greater than or equal to <= : Is less than or equal to != : Is not equal to + : Add - : Subtract / : Divide * : Multiply += : Plus equals && : And || : Or % : Remainder ^ : ??? : : Represents a key NEG: Negative f : Added to many arguments to apply to floats Logical Syntax if: Creates a conditional statement not: Reverses the conditions for a conditional statement jump: Jumps to a given key if conditions are met call: Calls a function by name return: Terminate function Some of these logical arguments can be used with or without being used in a conditional statement (explained later), while some can only be used in one of the two ways; others still are special cases, and are used differently. A single equal sign ( = ) and the plus equal sign ( += ) are the only ones on the list which can't be used in a conditional statement. " = " is mainly used to designate variables to various values in a standalone statement, and "+=" is used to add a number to a variable: Example: Gvar4 = Object("Object") var0 += 2 All of the equality arguments ( , >, <, >=, <=, != ) can only be used in a conditional statement. They are used to check if a certain value has a certain relation to another certain value: Example: if CurrentHealth(GetHost()) 50 jump 30 if var2 > 4 jump 12 if Gvar4 != Gvar5 jump 24 Plural reference arguments ( &&, || ) are also exclusive to conditional arguments; they detect whether or not the conditions apply to every -- or any, depending on which one is used -- reference specified: Example: if not Gvar65 Gvar2 && Gvar66 Gvar2 jump 22 if IsCaller(Gvar4) || IsCaller(Gvar5) jump 46 The math arguments ( + - / * % ) can be used both in declaration of variables and in commands. In standalone statements, they are often used to modify the original value of a variable; in some commands, they can be used inside arguments to specify more complex values: Example: var0 = var0 * var1 ChangeGold(Gvar1,CurrentHealth(Gvar1) + 1) Gvar4 = Gvar5 % 4 The colon ( : ) isn't used in any statements, but in keys. Keys are used to jump to certain sections of the script without executing anything inbetween. (NOTE: It is possible to create recursive loops that never end; these will lock up the game!) They are used with the logical syntax "jump". One such use of keys is to implement a "staircase" structure, shown in example: ---Gem Machine--- var0 += 1 if var0 1 jump 10 if var0 2 jump 20 if var0 3 jump 30 jump 40 :10 Create("Ruby",Gvar4) return :20 Create("Emerald",Gvar4) return :30 Create("Diamond",Gvar4) :40 var0 = 0 return When the script is refreshed, all keys will fix themselves to their correct value. A negative value (NEG) isn't really logic; it simply represents a negative integer, since you cannot use the minus sign to represent a negative value: ChangeScore(Gvar1,NEG 500) Float values (marked with an 'f' ) aren't logic either; float values can have decimals, unlike integers. All float values MUST be marked with an 'f', including numbers, variables, and math. For numbers and math, the 'f' is put at the beginning of said entity, while variables have an 'f' placed before the variable number. However, variables must first be declared normally, but it must be declared with an ' f= ' instead of just ' = '. Here are some examples to further clarify this process: var0 f= f30 var1 f= varF0 f+ f0.5 if not varF1 f>= varF0 jump 20 :20 return Logical syntax has been used many times throughout the examples, but has yet to have been discussed. There are five main arguments for logical syntax; if, not, jump, call, and return. The argument "if" begins a conditional statement; the contents that come afterwards is more or less arranged into an equality equation. If the equation is true, then the conditions are met, and the script will follow its rules. If it's false, then the script ignores the statement and moves on: if Gvar4 1 jump 20 if GetCaller() != GetHost() jump 30 The argument "not" is placed, if necessary, right after "if", and the conditions to be met are the opposite of what is stated: if not var0 >= 6 jump 13 The argument "jump" can be used either in a standalone statement or at the end of a conditional statement, and will jump to a specified key. If it is in a conditional statement, the conditions must first be met before "jump" is executed: jump 56 if CurrentHealth(Gvar1) < 1 jump 37 The argument "call" may only be used alone; it calls another function by name. Make sure you do not use this argument on itself, for it is possible to create a recursive loop, which can lock up the game: ---Correct Use--- Function 3: Caller call Receiver return Function 4: Receiver Create("Gold",Gvar4) return ---Incorrect Use--- Function 3: Repeater call Repeater return The argument "return" is used alone, and is one of the most important in script; when this command is hit, the script ends. All scripts must end with this.